Git is a tool for Version Control. Version Control is a tool for managing changes to files. According to Software Carpentry, it is better than Dropbox and Email because:
Nothing that is committed to version control is ever lost. Since all old versions of files are saved, it’s always possible to go back in time to see exactly who wrote what on a particular day, or what version of a program was used to generate a particular set of results.
As we have this record of who made what changes when, we know who to ask if we have questions later on, and, if needed it, revert to a previous version, much like the “undo” feature in an editor.
When several people collaborate in the same project, it’s possible to accidentally overlook or overwrite someone’s changes: the version control system automatically notifies users whenever there’s a conflict between one person’s work and another’s.
GitHub is a website that lets you share git repositories (collections of code) on it. It also gives you a web interface for reading and reviewing code. GitHub isn't the only website that does this, but it's the most common one. It's also the one used for Nengo and the CTN's other projects.
To learn how to use Git and GitHub in a thorough manner, going through the Software Carpentry Tutorial on Git is highly recommended. However, the aforementioned tutorial does not cover branches, an important feature of how Nengo uses Git, which are covered in this seperate tutorial in the same style as Software Carpentry.
Basically, if you want to make changes to code on GitHub, you'll generally follow the following pattern:
-> git clone <repositoryurl>
-> git checkout -b <newbranch>
-> git add <filechanged>
-> git commit -m "<commitmessage>
-> git push origin <newbranch>
master
branchIf you just want some commands to add your code to Nengo, see the next section.
Nengo uses a strict set of rules for using git
to ensure that the history of the master
branch is clean and readable.
Here is a handy summary of the commands you'll probably need (with commit
and add
ommitted, since they're very basic):
Make a new branch
git branch <newbranch>
git checkout <newbranch>
Shortcut! Make a new branch
git checkout -b <newbranch>
Push a new branch to a remote (in this case origin)
git push origin <newbranch>
Delete a branch locally
git branch -D <newbranch>
Delete a branch on a remote (in this origin)
git push origin :<newbranch>
Update master and rebase your branch to master
git checkout master
git pull
git checkout <newbranch>
git rebase master
Check out a remote branch (after pulling to see that there is a branch)
git checkout --track -b <newbranch> origin/<newbranch>
(For maintainers) Clean up commits on a branch (prepping for merge)
git checkout <branchtomerge>
git rebase master
git rebase -i <commit> # if you want to edit the history
(For maintainers) Merge a cleaned up branch
git checkout master
git merge <cleanbranch>
# Ensure that the history looks clean before pushing!
Given you're probably going to be collaborating with only one other person and you just want GitHub to be a nice public place for you to both put your code, you probably won't need as strict of a workflow as Nengo. You'll probably be fine working directly off the master
branch. In other words you won't make a new branch every time you want to change code. This is sometimes called the Centralised Workflow.
However, if conflicts start to become a problem, creating branches and reviewing before merging code is recommended. This is sometimes called the Feature Branch Workflow.
Automate checking that branches meet style guidelines and pass tests. Performed on Nengo with TravisCI.
GitHub has many tools for viewing who changed what and where they changed it.